# Wi-Fi Scan

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

# 功能概述

**Wi-Fi Scan（Wi‑Fi扫描）** 功能用于探测周围可用的Wi-Fi接入点（Access Point），并获取其详细信息（如服务集标识符SSID、基本服务集标识符BSSID、信号强度RSSI和信道等）。Wi-Fi Scan支持同步和异步两种工作模式，广泛应用于物联网设备、智能家居及网络管理等需要Wi-Fi网络环境检测的场景。

## 基本要素

1. **扫描发起实体**：触发Wi-Fi扫描操作的主体，通常是移动终端、物联网设备或Wi-Fi探测设备。

2. **扫描目标（AP）**：Wi-Fi扫描的对象，即周围提供无线网络服务的接入点AP，如无线路由器、热点设备。

3. **扫描参数**：控制扫描行为的配置项，包括扫描的信道范围、时长、间隔等，决定了扫描的覆盖范围与执行效率。

4. **信号捕获单元**：Wi-Fi射频前端硬件，负责接收周围AP射频信号，是AP信号采集的物理载体。

5. **扫描结果集**：Wi-Fi扫描后生成的信息集合，通常包含AP的SSID、RSSI、加密方式、BSSID等核心数据。

6. **射频信道**：Wi-Fi扫描所使用的无线频段信道，是AP与扫描实体之间的通信载体。

## 工作流程

Wi-Fi Scan是Wi‑Fi射频轮询探测、帧捕获、协议解析、数据规整的完整链路，依托信道快速切换与802.11帧解析实现AP信息采集，处理结果向上层业务交付的功能。具体工作流程如下：

1. **扫描初始化**：业务应用层下发扫描启动指令，Wi-Fi Scan功能完成射频单元、SPI/SDIO通信接口等硬件初始化及内部状态机初始化，完成后切换至扫描就绪状态，等待业务层配置扫描参数。

2. **扫描参数配置**：业务应用层下发扫描配置参数（信道范围、主动/被动模式、探测时长），Wi-Fi Scan功能依据配置生成信道切换时序与探测规则，预加载后续扫描执行逻辑。

3. **射频信道探测**：Wi-Fi Scan功能按预规划的信道序列切换射频链路，主动扫描向外发送探测请求帧、被动扫描监听Beacon广播，同步捕获AP的原始信号数据与RSSI。

4. **AP信息解析与整理**：Wi-Fi Scan功能对捕获的信号帧进行协议解析，提取SSID/BSSID等AP信息；对同BSSID重复数据做去重处理，并按照RSSI从高到低排序，生成结构化结果集。

5. **扫描结果反馈与缓存**：Wi-Fi Scan功能经由内部交互接口向业务应用层回传AP结果集，同时在本地缓存扫描数据以支持快速二次查询，最后释放本次扫描所用临时内存，归还占用的射频硬件资源。

## 扫描模式分类

基于程序流程是否阻塞，扫描模式分为同步扫描和异步扫描，详情如下：

1. **同步扫描**  
    - **对应函数**：*qosa_wifiscan_do()*  
    - **基本概念**：调用扫描函数后，当前线程会被阻塞，直到扫描完成并返回结果后，才能继续执行后续逻辑。  
    - **适用场景**：对流程顺序要求严格、无需并行处理其他任务的简单单次扫描需求。

2. **异步扫描（默认）**  
    - **对应函数**：*qosa_wifiscan_async()*  
    - **基本概念**：调用扫描函数后，当前线程不阻塞，可继续执行其他任务；扫描完成后，结果通过预先注册的回调函数 *qosa_wifiscan_register_cb()* 返回。  
    - **适用场景**：需要并行处理多任务、避免界面卡顿的场景（如UI交互过程中触发扫描）。

## 典型应用场景

- 物联网设备的Wi-Fi网络环境检测与最优网络选择。

- 智能家居设备的网络连接与配网。

- 网络管理工具的Wi-Fi环境分析。

- 需要定期监控Wi-Fi网络状态的应用场景。

# Wi-Fi Scan API

## 头文件

*qosa_wifiscan.h*

## 函数概览

| **函数** | **说明** |
| --- | --- |
| *qosa_wifiscan_open()* | 启用Wi-Fi Scan |
| *qosa_wifiscan_close()* | 关闭Wi-Fi Scan |
| *qosa_wifiscan_do()* | 开始Wi-Fi Scan同步模式扫描 |
| *qosa_wifiscan_async()* | 开始Wi-Fi Scan异步模式扫描 |
| *qosa_wifiscan_option_set()* | 配置Wi-Fi Scan扫描参数 |
| *qosa_wifiscan_get_config()* | 获取Wi-Fi Scan配置参数 |
| *qosa_wifiscan_register_cb()* | 注册异步扫描回调函数 |

## 函数详解

### qosa_wifiscan_open

- **功能描述**  
  启用Wi-Fi Scan。在使用其他Wi-Fi Scan功能前，必须先调用此函数启用Wi-Fi Scan。

- **函数原型**

```c
qosa_wifiscan_error_e qosa_wifiscan_open(void)
```

- **参数说明**  
  无

- **返回值说明**  
  *QOSA_WIFISCAN_SUCCESS*：函数执行成功  
  *QOSA_WIFISCAN_OPEN_FAIL*：Wi-Fi Scan启用异常  
  *QOSA_WIFISCAN_ALREADY_OPEN_ERR*：Wi-Fi Scan重复启用错误  
  *QOSA_WIFISCAN_HW_OCCUPIED_ERR*：硬件被占用  
  其他值详见 [*qosa_wifiscan_error_e*](#qosawifiscanerror_e)

### qosa_wifiscan_close

- **功能描述**  
  关闭Wi-Fi Scan。扫描完成后须调用此函数关闭Wi-Fi Scan功能，释放相关资源。

- **函数原型**

```c
qosa_wifiscan_error_e qosa_wifiscan_close(void)
```

- **参数说明**  
  无

- **返回值说明**  
  *QOSA_WIFISCAN_SUCCESS*：函数执行成功  
  其他值详见 [*qosa_wifiscan_error_e*](#qosawifiscanerror_e)

### qosa_wifiscan_do

- **功能描述**  
  开始Wi-Fi Scan同步模式扫描。调用此函数后，当前线程会被阻塞直至扫描完成，扫描结果直接返回。

- **函数原型**

```c
qosa_wifiscan_error_e qosa_wifiscan_do(
    qosa_uint16_t *p_ap_cnt,
    qosa_wifi_ap_info_t *p_ap_infos
)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *p_ap_cnt* | 输出 | qosa_uint16_t | 扫描到的AP数量 |
| *p_ap_infos* | 输出 | *qosa_wifi_ap_info_t* | 扫描获取的每个AP信息；详见 [*qosa_wifi_ap_info_t*](#qosawifiapinfot) |

- **返回值说明**  
  *QOSA_WIFISCAN_SUCCESS*：函数执行成功  
  其他值详见 [*qosa_wifiscan_error_e*](#qosawifiscanerror_e)

### qosa_wifiscan_async

- **功能描述**  
  开始Wi-Fi Scan异步模式扫描。调用此函数后，当前线程不会被阻塞，扫描结果通过注册的回调函数 ***qosa_wifiscan_register_cb()*** 返回。

- **函数原型**

```c
qosa_wifiscan_error_e qosa_wifiscan_async(void)
```

- **参数说明**  
  无

- **返回值说明**  
  *QOSA_WIFISCAN_SUCCESS*：函数执行成功  
  其他值详见 [*qosa_wifiscan_error_e*](#qosawifiscanerror_e)

### qosa_wifiscan_option_set

- **功能描述**  
  配置Wi-Fi Scan扫描参数。

- **函数原型**

```c
qosa_wifiscan_error_e qosa_wifiscan_option_set(
    qosa_wifiscan_config_t *wifiscan_config
)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *wifiscan_config* | 输入 | *qosa_wifiscan_config_t* | Wi-Fi Scan扫描参数；详见 [*qosa_wifiscan_config_t*](#qosawifiscanconfig_t) |

- **返回值说明**  
  *QOSA_WIFISCAN_SUCCESS*：函数执行成功  
  其他值详见 [*qosa_wifiscan_error_e*](#qosawifiscanerror_e)

### qosa_wifiscan_get_config

- **功能描述**  
  获取Wi-Fi Scan配置参数。

- **函数原型**

```c
qosa_wifiscan_error_e qosa_wifiscan_get_config(
    qosa_wifiscan_config_t *wifiscan_config
)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *wifiscan_config* | 输出 | *qosa_wifiscan_config_t* | Wi-Fi Scan扫描参数；详见 [*qosa_wifiscan_config_t*](#qosawifiscanconfig_t) |

- **返回值说明**  
  *QOSA_WIFISCAN_SUCCESS*：函数执行成功  
  *QOSA_WIFISCAN_MEM_ADDR_NULL_ERR*：内存分配失败  
  其他值详见 [*qosa_wifiscan_error_e*](#qosawifiscanerror_e)

### qosa_wifiscan_register_cb

- **功能描述**  
  注册异步扫描回调函数。当异步扫描完成时，系统会调用此回调函数返回扫描结果。

- **函数原型**

```c
qosa_wifiscan_error_e qosa_wifiscan_register_cb(
    qosa_wifiscan_callback wifiscan_cb,
    void *user_data
)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *wifiscan_cb* | 输入 | *qosa_wifiscan_callback* | 回调函数指针；详见 [*qosa_wifiscan_callback*](#qosawifiscancallback) |
| *user_data* | 输入 | void | 用户自定义数据指针 |

#### qosa_wifiscan_callback

- **函数原型**

```c
typedef void (*qosa_wifiscan_callback)(
    void *user_data,
    qosa_wifiscan_error_e result,
    qosa_uint32_t ap_cnt,
    qosa_wifi_ap_info_t *ap_infos
)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *user_data* | 输入 | void | 异步回调用户数据 |
| *result* | 输入 | *qosa_wifiscan_error_e* | 扫描结果码；详见 [*qosa_wifiscan_error_e*](#qosawifiscanerror_e) |
| *ap_cnt* | 输入 | qosa_uint32_t | 扫描到的AP数量 |
| *ap_infos* | 输入 | *qosa_wifi_ap_info_t* | 扫描获取的每个AP信息；详见 [*qosa_wifi_ap_info_t*](#qosawifiapinfot) |

- **返回值说明**  
  *QOSA_WIFISCAN_SUCCESS*：函数执行成功  
  *QOSA_WIFISCAN_INVALID_PARAM_ERR*：无效参数  
  QOSA_WIFISCAN_ALREADY_OPEN_ERR：Wi-Fi Scan重复启用错误  
  其他值详见 [*qosa_wifiscan_error_e*](#qosawifiscanerror_e)

## 结构体定义

### qosa_wifi_ap_info_t

扫描获取的每个AP信息结构体定义如下：

```c
typedef struct
{
    qosa_uint8_t bssid[6]; 
    qosa_uint8_t channel; 
    qosa_int8_t  rssival;  
    qosa_uint8_t ssid_len;
    qosa_uint8_t ssid[33]; 
    char         reserve; 
} qosa_wifi_ap_info_t
```

| **参数** | **类型** | **说明** |
| --- | --- | --- |
| *bssid* | qosa_uint8_t | Wi-Fi AP的MAC地址 |
| *channel* | qosa_uint8_t | AP工作的信道 |
| *rssival* | qosa_int8_t | AP的信号强度；单位：dBm |
| *ssid_len* | qosa_uint8_t | SSID长度 |
| *ssid* | qosa_uint8_t | Wi-Fi AP的SSID名称 |
| *reserve* | char | 预留字段 |

### qosa_wifiscan_config_t

Wi-Fi Scan扫描参数结构体定义如下：

```c
typedef struct
{
    qosa_uint16_t           max_ap_cnt; 
    qosa_wifiscan_channel_e channel;    
    qosa_uint8_t            scan_round; 
    qosa_uint32_t           ch_time;   
    qosa_uint32_t max_timeout;
    qosa_uint32_t scan_timeout;           
    qosa_uint8_t  wifi_priority;       
} qosa_wifiscan_config_t
```

| **参数** | **类型** | **说明** |
| --- | --- | --- |
| *max_ap_cnt* | qosa_uint16_t | Wi-Fi Scan可探测的最大AP数量 |
| *channel* | *qosa_wifiscan_channel_e* | Wi-Fi Scan信道（1个比特位表示1个信道）；详见 [*qosa_wifiscan_channel_e*](#qosawifiscanchannel_e) |
| *scan_round* | qosa_uint8_t | Wi-Fi Scan扫描轮次 |
| *ch_time* | qosa_uint32_t | 每轮扫描中，每个信道的最长驻留扫描时长；单位：毫秒 |
| *max_timeout* | qosa_uint32_t | 单次Wi-Fi Scan扫描请求的最大扫描时长；单位：毫秒 |
| *scan_timeout* | qosa_uint32_t | 每一轮扫描的最大超时时间；单位：秒 |
| *wifi_priority* | qosa_uint8_t | Wi-Fi Scan扫描优先级  <br>*0*：数据优先；扫描过程中优先保障数据传输不中断  <br>*1*：Wi-Fi扫描优先；优先保障扫描的信道侦听与数据捕获 |

## 枚举定义

### qosa_wifiscan_error_e

Wi-Fi Scan扫描结果码枚举定义如下：

```c
typedef enum
{
    QOSA_WIFISCAN_SUCCESS = 0,                                            
    QOSA_WIFISCAN_EXECUTE_ERR = (QOSA_COMPONENT_WIFISCAN << 16) | 1,     
    QOSA_WIFISCAN_MEM_ADDR_NULL_ERR = (QOSA_COMPONENT_WIFISCAN << 16) | 2,  
    QOSA_WIFISCAN_INVALID_PARAM_ERR = (QOSA_COMPONENT_WIFISCAN << 16) | 3,  
    QOSA_WIFISCAN_SEMAPHORE_WAIT_ERR = (QOSA_COMPONENT_WIFISCAN << 16) | 4, 
    QOSA_WIFISCAN_MUTEX_TIMEOUT_ERR = (QOSA_COMPONENT_WIFISCAN << 16) | 5,  
    QOSA_WIFISCAN_OPEN_FAIL = (QOSA_COMPONENT_WIFISCAN << 16) | 6,         
    QOSA_WIFISCAN_BUSY_ERR = (QOSA_COMPONENT_WIFISCAN << 16) | 7,          
    QOSA_WIFISCAN_ALREADY_OPEN_ERR = (QOSA_COMPONENT_WIFISCAN << 16) | 8, 
    QOSA_WIFISCAN_NOT_OPEN_ERR = (QOSA_COMPONENT_WIFISCAN << 16) | 9,      
    QOSA_WIFISCAN_HW_OCCUPIED_ERR = (QOSA_COMPONENT_WIFISCAN << 16) | 10,   
    QOSA_WIFISCAN_NO_SET_CB_ERR = (QOSA_COMPONENT_WIFISCAN << 16) | 11,   
} qosa_wifiscan_error_e
```

| **成员** | **说明** |
| --- | --- |
| *QOSA_WIFISCAN_SUCCESS* | 函数执行成功 |
| *QOSA_WIFISCAN_EXECUTE_ERR* | 函数执行失败 |
| *QOSA_WIFISCAN_MEM_ADDR_NULL_ERR* | 内存申请失败 |
| *QOSA_WIFISCAN_INVALID_PARAM_ERR* | 无效参数 |
| *QOSA_WIFISCAN_SEMAPHORE_WAIT_ERR* | 信号量等待异常 |
| *QOSA_WIFISCAN_MUTEX_TIMEOUT_ERR* | 互斥锁获取异常 |
| *QOSA_WIFISCAN_OPEN_FAIL* | Wi-Fi Scan启用异常 |
| *QOSA_WIFISCAN_BUSY_ERR* | Wi-Fi Scan忙碌，如正在进行扫描 |
| *QOSA_WIFISCAN_ALREADY_OPEN_ERR* | Wi-Fi Scan重复启用错误 |
| *QOSA_WIFISCAN_NOT_OPEN_ERR* | Wi-Fi Scan未启用 |
| *QOSA_WIFISCAN_HW_OCCUPIED_ERR* | 硬件被占用 |
| *QOSA_WIFISCAN_NO_SET_CB_ERR* | 未配置回调函数 |

### qosa_wifiscan_channel_e

Wi-Fi Scan信道枚举定义如下：

```c
typedef enum
{
    QOSA_WIFISCAN_CHANNEL_ALL_BIT = 0x1FFF,
    QOSA_WIFISCAN_CHANNEL_ONE = 0x0001,     
    QOSA_WIFISCAN_CHANNEL_TWO = 0x0002,     
    QOSA_WIFISCAN_CHANNEL_THREE = 0x0004,  
    QOSA_WIFISCAN_CHANNEL_FOUR = 0x0008,   
    QOSA_WIFISCAN_CHANNEL_FIVE = 0x0010,    
    QOSA_WIFISCAN_CHANNEL_SIX = 0x0020,     
    QOSA_WIFISCAN_CHANNEL_SEVEN = 0x0040,   
    QOSA_WIFISCAN_CHANNEL_EIGHT = 0x0080,  
    QOSA_WIFISCAN_CHANNEL_NINE = 0x0100,    
    QOSA_WIFISCAN_CHANNEL_TEN = 0x0200,    
    QOSA_WIFISCAN_CHANNEL_ELEVEN = 0x0400, 
    QOSA_WIFISCAN_CHANNEL_TWELVE = 0x0800, 
    QOSA_WIFISCAN_CHANNEL_THIRTEEN = 0x1000, 
} qosa_wifiscan_channel_e
```

| **成员** | **说明** |
| --- | --- |
| *QOSA_WIFISCAN_CHANNEL_ALL_BIT* | 扫描所有信道（位掩码组合值，涵盖信道1~13） |
| *QOSA_WIFISCAN_CHANNEL_ONE* | 信道1 |
| *QOSA_WIFISCAN_CHANNEL_TWO* | 信道2 |
| *QOSA_WIFISCAN_CHANNEL_THREE* | 信道3 |
| *QOSA_WIFISCAN_CHANNEL_FOUR* | 信道4 |
| *QOSA_WIFISCAN_CHANNEL_FIVE* | 信道5 |
| *QOSA_WIFISCAN_CHANNEL_SIX* | 信道6 |
| *QOSA_WIFISCAN_CHANNEL_SEVEN* | 信道7 |
| *QOSA_WIFISCAN_CHANNEL_EIGHT* | 信道8 |
| *QOSA_WIFISCAN_CHANNEL_NINE* | 信道9 |
| *QOSA_WIFISCAN_CHANNEL_TEN* | 信道10 |
| *QOSA_WIFISCAN_CHANNEL_ELEVEN* | 信道11 |
| *QOSA_WIFISCAN_CHANNEL_TWELVE* | 信道12 |
| *QOSA_WIFISCAN_CHANNEL_THIRTEEN* | 信道13 |

# 应用逻辑流程图

## 同步扫描

```{figure} images/board_PQvTw0itzhg25zbRrUAcDcSon9q.jpg
:align: center
:alt: image
```

## 异步扫描

```{figure} images/board_RDW3w7mZthmdpfbX18Bcqqwxn48.jpg
:align: center
:alt: image
```

# 示例代码

同步扫描完整示例代码请查看 https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/network/location/wifiscan/wifiscan_sync.c

异步扫描完整示例代码请查看 https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/network/location/wifiscan/wifiscan_asyn.c

# 开发约束与使用规范

1. **参数配置**

扫描参数 *qosa_wifiscan_config_t* 必须在成功调用 *qosa_wifiscan_open()* 前完成配置。Wi-Fi Scan启用后，再次调用 *qosa_wifiscan_option_set()* 将返回 *QOSA_WIFISCAN_ALREADY_OPEN_ERR* 报错。

2. **设备状态管理**

使用扫描接口遵循先打开、后关闭调用规范：开始扫描前必须先调用 *qosa_wifiscan_open()* 启用Wi-Fi Scan功能；业务结束后应调用 *qosa_wifiscan_close()* 关闭Wi-Fi Scan功能、释放资源。

3. **内存管理**

- 同步扫描模式：调用者需要负责分配和释放 *p_ap_infos* 指向的内存空间。

- 异步扫描模式：系统自动管理 *ap_infos* 内存空间，回调函数中无需手动释放。

4. **扫描模式选择**

- 同步扫描：调用任务阻塞至扫描全流程结束，适用于需要立即获取扫描结果的场景。

- 异步扫描：扫描结果通过回调函数返回，适用于不希望阻塞当前线程的场景。

5. **资源竞争**

Wi-Fi Scan和LTE共享射频资源，只有当LTE处于RRC Idle状态时才可正常启动Wi‑Fi扫描。

6. **硬件占用**

Wi-Fi Scan可能与蓝牙等其他无线功能共享硬件，在使用时可能遇到硬件被占用的情况。